Install the SDK, wrap your first tool, and see governance in action in under 2 minutes.

Quick Start

Choose your path — from fastest to most flexible.

Option 1: Scaffolding CLI (fastest)

Create a fully working project with one command:

npx create-sidclaw-app my-governed-agent

The CLI walks you through:

Framework — LangChain (Python/JS), Vercel AI, OpenAI Agents, MCP Proxy, or plain TS/Python
API key — paste an existing key or sign up at app.sidclaw.com
Setup — creates a project with a registered agent, 3 demo policies, and a working governance example

cd my-governed-agent
npm start   # or: python main.py (for Python templates)

Open the dashboard at app.sidclaw.com (or localhost:3000 if self-hosting) to see approval requests and audit traces.

Option 2: TypeScript SDK

1. Install the SDK

npm install @sidclaw/sdk

2. Get an API Key

SidClaw Cloud: Sign up at sidclaw.com, go to Settings > API Keys > Create Key.

Running locally: The key is printed when you seed the database:

cd apps/api && npx prisma db seed
# → API key: sk_dev_...

The seed key is also saved to deployment/.env.development.

3. Register an Agent

Every agent needs an identity before it can be governed. Create one through the dashboard or the API:

Via dashboard: Open Agents > Create Agent. Fill in a name, owner, and environment. Copy the agent ID (e.g., ag_abc123).

Via API:

curl -X POST https://api.sidclaw.com/api/v1/agents \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My First Agent",
    "description": "Testing SidClaw governance",
    "owner_name": "Your Name",
    "owner_role": "Developer",
    "team": "Engineering",
    "environment": "dev",
    "authority_model": "delegated",
    "identity_mode": "delegated_identity",
    "delegation_model": "on_behalf_of_user",
    "autonomy_tier": "medium",
    "created_by": "[email protected]"
  }'
# → { "data": { "id": "ag_abc123", ... } }

Copy the id from the response — you'll use it in the next step.

Running locally: The database seed creates a demo agent automatically. Its ID is printed in the seed output.

4. Initialize the Client

import { AgentIdentityClient } from '@sidclaw/sdk';

const client = new AgentIdentityClient({
  apiKey: process.env.SIDCLAW_API_KEY!,
  apiUrl: 'https://api.sidclaw.com',  // or http://localhost:4000
  agentId: 'ag_abc123',               // from step 3
});

5. Wrap Your Agent's Tools

Use withGovernance() to wrap any async function with policy evaluation and approval handling:

import { withGovernance } from '@sidclaw/sdk';

const sendEmail = withGovernance(client, {
  operation: 'send_email',
  target_integration: 'email_service',
  resource_scope: 'customer_emails',
  data_classification: 'confidential',
}, async (to: string, subject: string, body: string) => {
  await emailService.send({ to, subject, body });
});

// Now governed — call it normally:
await sendEmail('[email protected]', 'Follow-up', 'Hello...');

When your agent calls sendEmail, the SDK:

Sends the action details to POST /api/v1/evaluate
The Policy Engine matches the action against your rules
Based on the policy decision:
- allow — Executes the function immediately and records the outcome
- approval_required — Polls until a human reviewer approves or denies, then executes or throws
- deny — Throws ActionDeniedError without executing

import { ActionDeniedError, ApprovalExpiredError } from '@sidclaw/sdk';

try {
  await sendEmail('[email protected]', 'Follow-up', 'Hello...');
} catch (error) {
  if (error instanceof ActionDeniedError) {
    console.log('Blocked by policy:', error.reason);
    console.log('Trace ID:', error.traceId);
  }
  if (error instanceof ApprovalExpiredError) {
    console.log('No reviewer responded in time');
  }
}

6. See It in Action

Run your agent and open the dashboard at localhost:3000 (or your SidClaw Cloud dashboard).

Approval Queue — If the action requires approval, you will see a card with the operation details, risk classification, and the agent's context. Approve or deny it.
Trace Viewer — Every evaluated action produces an audit trace. Click into a trace to see the full event chain: identity resolution, policy evaluation, approval decision, and execution outcome.

Option 3: Python SDK

1. Install

pip install sidclaw

2. Initialize

from sidclaw import SidClaw

client = SidClaw(
    api_key="your-api-key",
    agent_id="your-agent-id",
)

3. Govern your tools

from sidclaw.middleware.generic import with_governance, GovernanceConfig

@with_governance(client, GovernanceConfig(
    operation="send_email",
    target_integration="email_service",
    data_classification="confidential",
))
def send_email(to, subject, body):
    email_service.send(to=to, subject=subject, body=body)

send_email("[email protected]", "Follow-up", "Hello...")

4. Handle errors

from sidclaw import ActionDeniedError, ApprovalExpiredError

try:
    send_email("[email protected]", "Follow-up", "Hello...")
except ActionDeniedError as e:
    print(f"Blocked by policy: {e.reason}")
    print(f"Trace ID: {e.trace_id}")
except ApprovalExpiredError:
    print("No reviewer responded in time")

5. See It in Action

Run your agent and open the dashboard. The experience is the same as with the TypeScript SDK — approval queue, trace viewer, and all other features work identically.

Next Steps

Python SDK Reference — Full Python SDK documentation with sync/async clients and framework wrappers
create-sidclaw-app — Details on scaffolding templates and options
Agent Identity — Understand agent registration, lifecycle states, and authority models
Policies — Write your first policy rule and test it with dry-run
Approvals — Learn about approval workflows, expiry, and separation of duties
Audit Traces — Explore the event chain and integrity verification

Quick Start

On this page